Events
jsPlumb supports binding to several different events on Connections, Endpoints and Overlays, and also on the jsPlumb object itself.
jsPlumb Events
To bind an to event on jsPlumb itself (or a jsPlumb instance), use jsPlumb.bind(event, callback)
:
jsPlumb.bind("connection", function(info) {
.. update your model in here, maybe.
});
These are the events you can bind to on the jsPlumb class:
connection
- notification a Connection was established.
The first argument to the callback is an object with the following properties:
{
connection : the new Connection. you can register listeners on this etc.
sourceId : id of the source element in the Connection
targetId : id of the target element in the Connection
source : the source element in the Connection
target : the target element in the Connection
sourceEndpoint : the source Endpoint in the Connection
targetEndpoint : the targetEndpoint in the Connection
}
The second argument is the original mouse event that caused the Connection, if any.
All of the source/target properties are actually available inside the Connection object, but - for one of those rubbish historical reasons - are provided separately because of a vagary of the connectionDetached
callback, which is discussed below.
connectionDetached
- notification a Connection was detached.
As with connection
, the first argument to the callback is an object with the following properties:
{
connection : the Connection that was detached.
sourceId : id of the source element in the Connection <em>before it was detached</em>
targetId : id of the target element in the Connection before it was detached
source : the source element in the Connection before it was detached
target : the target element in the Connection before it was detached
sourceEndpoint : the source Endpoint in the Connection before it was detached
targetEndpoint : the targetEndpoint in the Connection before it was detached
}
The second argument is the original mouse event that caused the disconnection, if any.
As mentioned above, the source
/target
properties are provided separately from the Connection, because this event is fired whenever a Connection is either detached and abandoned, or detached from some Endpoint and attached to another. In the latter case, the Connection that is passed to this callback is in an indeterminate state (that is, the Endpoints are still in the state they are in when dragging, and do not reflect static reality), and so the source
/target
properties give you the real story.
connectionDrag
- notification an existing Connection is being dragged. The callback is passed the Connection. Note that when this event fires for a brand new Connection, the target of the Connection is a transient element that jsPlumb is using for dragging, and will be removed from the DOM when the Connection is subsequently either established or aborted.connectionDragStop
- notification a Connection drag has stopped. This is only fired for existing Connections. The callback is passed the Connection that was just dragged.click
- notification a Connection was clicked. The callback is passed the Connection and the original mouse event.dblclick
- notification a Connection was double-clicked. The callback is passed the Connection and the original mouse event.endpointClick
- notification an Endpoint was clicked. The callback is passed the Endpoint and the original mouse event.endpointDblClick
- notification an Endpoint was double-clicked. The callback is passed the Endpoint and the original mouse event.contextmenu
- a right-click on some given component. jsPlumb will report right clicks on both Connections and Endpoints; the callback is passed the component that received the right-click.beforeDrop
This event is fired when a new or existing connection has been dropped. Your callback is passed a JS object with these fields:<ul> <li><strong>sourceId</strong> - the id of the source element in the connection</li> <li><strong>targetId</strong> - the id of the target element in the connection</li> <li><strong>scope</strong> - the scope of the connection</li> <li><strong>connection</strong> - the actual Connection object. You can access the 'endpoints' array in a Connection to get the Endpoints involved in the Connection, but be aware that when a Connection is being dragged, one of these Endpoints will always be a transient Endpoint that exists only for the life of the drag. To get the Endpoint on which the Connection is being dropped, use the `dropEndpoint` member.</li> <li><strong>dropEndpoint</strong> - this is the actual Endpoint on which the Connection is being dropped. This <strong>may be null</strong>, because it will not be set if the Connection is being dropped on an element on which makeTarget has been called. </li> </ul>
If you return false (or nothing) from this callback, the new Connection is aborted and removed from the UI.
beforeDetach
This event is fired when a Connection is about to be detached, for whatever reason. Your callback function is passed the Connection that the user has just detached. Returning false from this interceptor aborts the Connection detach.
Connection Events
To bind to an event on a Connection, you also use the bind
method:
var connection = jsPlumb.connect({source:"d1", target:"d2"});
connection.bind("click", function(conn) {
console.log("you clicked on ", conn);
});
These are the Connection events to which you can bind a listener:
click
- notification a Connection was clicked. The callback is passed the Connection and the original mouse event.dblclick
- notification a Connection was double-clicked. The callback is passed the Connection and the original mouse event.contextmenu
- a right-click on the Connection. The callback is passed the Connection and the original event.mouseenter
- notification the mouse entered the Connection's path. The callback is passed the Connection and the original mouse event.mouseexit
- notification the mouse exited the Connection's. The callback is passed the Connection and the original mouse event.mousedown
- notification the mouse button was pressed on the Connection's path. The callback is passed the Connection and the original mouse event.mouseup
- notification the mouse button was released on the Connection's path. The callback is passed the Connection and the original mouse event.
Endpoint Events
To bind to an event on a Endpoint, you again use the bind
method:
var endpoint = jsPlumb.addEndpoint("d1", { someOptions } );
endpoint.bind("click", function(endpoint) {
console.log("you clicked on ", endpoint);
});
These are the Endpoint events to which you can bind a listener:
click
- notification an Endpoint was clicked. The callback is passed the Endpoint and the original mouse event.dblclick
- notification an Endpoint was double-clicked. The callback is passed the Endpoint and the original mouse event.contextmenu
- a right-click on the Endpoint. The callback is passed the Endpoint and the original event.mouseenter
- notification the mouse entered the Endpoint. The callback is passed the Endpoint and the original mouse event.mouseexit
- notification the mouse exited the Endpoint. The callback is passed the Endpoint and the original mouse event.mousedown
- notification the mouse button was pressed on the Endpoint. The callback is passed the Connection and the original mouse event.mouseup
- notification the mouse button was released on the Endpoint. The callback is passed the Connection and the original mouse event.maxConnections
- notification the user tried to drop a Connection on an Endpoint that already has the maximum number of Connections. The callback is passed as first argument an object literal containing the Endpoint, the Connection the user tried to drop, and the value of maxConnections for the Endpoint, and as second argument the original mouse event.
Overlay Events
Registering event listeners on an Overlay is a slightly different procedure - you provide them as arguments to the Overlay's constructor. This is because you never actually act on an Overlay object.
Here's how to register a click listener on an Overlay:
jsPlumb.connect({
source:"el1",
target:"el2",
overlays:[
[ "Label", {
events:{
click:function(labelOverlay, originalEvent) {
console.log("click on label overlay for :" + labelOverlay.component);
}
}
}],
[ "Diamond", {
events:{
dblclick:function(diamondOverlay, originalEvent) {
console.log("double click on diamond overlay for : " + diamondOverlay.component);
}
}
}]
]
});
The related component for an Overlay is available to you as the component
member of the Overlay.
Note that events registered on Diamond, Arrow or PlainArrow overlays will not fire with the Canvas renderer - they work only with the SVG and VML renderers.
Unbinding Events
On the jsPlumb object and on Connections and Endpoints, you can use the unbind
method to remove a listener. This method either takes the name of the event to unbind:
jsPlumb.unbind("click");
...or no argument, meaning unbind all events:
var e = jsPlumb.addEndpoint("someDiv");
e.bind("click", function() { ... });
e.bind("dblclick", function() { ... });
...
e.unbind("click");